import SEO from "../components/SEO";

<SEO
	title="Portal"
	description="Create and append a DOM node to the end of an HTML document and render a React tree into it"
/>

# Portal

Creates and appends a DOM node to the end of `document.body` and renders a React tree into it. Useful for rendering a natural React element hierarchy with a different DOM hierarchy to prevent parent styles from clipping or hiding content (for popovers, dropdowns, and modals).

```jsx
// jsx-demo
function Example() {
	return (
		<div style={{ height: 50, overflow: "auto" }}>
			<div style={{ border: "solid 5px", padding: 20, marginLeft: 170 }}>
				This is the React Root where the portal is rendered. You can see it has
				clipped overflow, but the portal's styles are just fine.
			</div>
			<Portal>
				<div
					style={{
						position: "absolute",
						top: 20,
						right: 20,
						width: 200,
						border: "solid 1px hsla(0, 0%, 0%, 0.25)",
						boxShadow: "0px 2px 10px hsla(0, 0%, 0%, 0.25)",
						padding: 20,
						background: "#f0f0f0",
						textAlign: "center",
					}}
				>
					This is in the portal
				</div>
			</Portal>
		</div>
	);
}
```

## Installation

From the command line in your project directory, run `npm install @reach/portal` or `yarn add @reach/portal`. Then import the component:

```bash
npm install @reach/portal
# or
yarn add @reach/portal
```

```js
import { Portal } from "@reach/portal";
```

## Component API

### Portal

Renders content inside of a portal at the end of the DOM tree.

#### Portal Props

| Prop                            | Type   | Required |
| ------------------------------- | ------ | -------- |
| [`children`](#children)         | node   | true     |
| [`type`](#type)                 | string | false    |
| [`containerRef`](#containerRef) | ref    | false    |

##### Portal children

`children: React.ReactNode`

Any content you want to render inside of the portal.

```jsx
<Portal>
	<div>Stuff goes here</div>
</Portal>
```

##### Portal type

`type?: string`

The DOM element type to render. If not set the portal will render a
`reach-portal` custom element.

##### Portal containerRef

`containerRef?: React.RefObject<Node>`

The container ref to which the portal will be appended. If not set the portal
will be appended to the body of the component's owner document (typically this
is the `document.body`).
